_bleio: LE Secure Connections numeric-comparison pairing - #11340

Motivation

Today a CircuitPython BLE peripheral can only do legacy Just Works pairing. Nothing surfaces a passkey or numeric-comparison value to Python, and the espressif port additionally raises NotImplementedError for any characteristic constructed with an *_WITH_MITM permission. So a peripheral that has a display and a button — a lock, a medical device, anything handling data that shouldn't cross an unauthenticated link — has no way to require a man-in-the-middle-protected bond.

This adds LE Secure Connections numeric comparison to _bleio, implemented on the espressif port. NimBLE already ships the SC crypto (MYNEWT_VAL_BLE_SM_SC), so this is a configuration + event-plumbing change, not a crypto port. nordic, silabs and zephyr-cp get stubs (see Per-port status).

New API — shared-bindings/_bleio/Connection

Numeric comparison is triggered automatically: constructing a Characteristic or Descriptor with read_perm/write_perm == Attribute.LESC_ENCRYPT_WITH_MITM now (a) maps to NimBLE's _AUTHEN GATT flags instead of raising, and (b) tells the adapter to advertise numeric-comparison-capable IO. A central that then pairs to reach that characteristic gets the numeric-comparison flow; the peripheral polls pairing_numeric_comparison, shows the digits, and calls confirm_pairing().

Design: per-characteristic permission drives adapter SM config

The permission flags (layer 2, per-attribute enforcement) drive the adapter's SM configuration (layer 1, pairing negotiation), not the other way around:

• common_hal_bleio_adapter_set_enabled() keeps the legacy defaults — sm_io_cap = NO_IO, sm_mitm = 0. Existing headless peripherals pair exactly as before.
• sm_sc = 1 is now set unconditionally. It's negotiated per pairing (a peer that only does legacy pairing still works), it's strictly better crypto, and numeric comparison requires it.
• The first time a Characteristic/Descriptor is constructed with a *_WITH_MITM permission, bleio_adapter_enable_mitm_pairing() raises ble_hs_cfg.sm_io_cap to DISPLAY_YESNO and sm_mitm to 1. This is a one-way, idempotent bump for the lifetime of the adapter.

This avoids regressing headless espressif peripherals that pair with a central which negotiates MITM: an unconditional DISPLAY_YESNO would leave them with a PASSKEY_ACTION they can't answer and a 30 s SM timeout.

espressif implementation

• Characteristic.c / Descriptor.c: delete the mp_raise_NotImplementedError("MITM security not supported") block; map ENC_WITH_MITM / LESC_ENC_WITH_MITM / SIGNED_* to _AUTHEN (NimBLE's GATT layer has no distinct LESC or signed flag).
• Connection.c: a new PAIR_WAITING_NUMCMP pairing state holds the value from BLE_GAP_EVENT_PASSKEY_ACTION; confirm_pairing() injects the answer with ble_sm_inject_io(). BLE_GAP_EVENT_ENC_CHANGE records desc.sec_state.authenticated as Connection.authenticated. A passkey action this device can't service (INPUT / OOB) terminates the link with BLE_ERR_AUTH_FAIL rather than stalling SM until its timeout.
• bleio_attribute_security_mode_requires_mitm() — small predicate in shared-module/_bleio/Attribute.c.

Per-port status

Not in scope / follow-ups

• Nordic (and the other ports') implementations — see above.
• Passkey entry / DISPLAY_ONLY / KEYBOARD_ONLY — only numeric comparison (DisplayYesNo) is handled; other IO capabilities are rejected.
• The blocking Connection.pair() is unchanged and doesn't drive numeric comparison — interactive pairing is inherently the non-blocking poll API.

Testing

Peripheral-side usage looks like this — the only thing that opts a peripheral into numeric comparison is giving a characteristic the LESC_ENCRYPT_WITH_MITM permission:

import time
import _bleio

# Requires a numeric-comparison-authenticated bond to read. Constructing it with
# this perm is the whole opt-in; the adapter starts offering numeric comparison.
service = _bleio.Service(_bleio.UUID("f0000100-1111-2222-3333-444455556666"))
secret = _bleio.Characteristic.add_to_service(
    service,
    _bleio.UUID("f0000101-1111-2222-3333-444455556666"),
    properties=_bleio.Characteristic.READ,
    read_perm=_bleio.Attribute.LESC_ENCRYPT_WITH_MITM,
    max_length=4,
    initial_value=b"\xde\xad\xbe\xef",
)

name = b"fancy-smart-lock"
adv = bytes((2, 0x01, 0x06, len(name) + 1, 0x09)) + name  # Flags + Complete Local Name

while True:
    _bleio.adapter.start_advertising(adv, connectable=True)
    while not _bleio.adapter.connected:
        time.sleep(0.1)
    _bleio.adapter.stop_advertising()
    connection = _bleio.adapter.connections[0]

    # The central hits `secret`, which needs an authenticated link, so it starts
    # LE Secure Connections pairing. Service the numeric-comparison prompt:
    while connection.connected and not connection.authenticated:
        code = connection.pairing_numeric_comparison
        if code is not None:
            print(f"pair? {code:06d}")          # show on a display; button = accept/reject
            connection.confirm_pairing(accept=True)
        time.sleep(0.1)

    if connection.connected:
        print("authenticated:", connection.authenticated)   # -> True; `secret` now readable

    while connection.connected:
        time.sleep(0.1)

• Built for espressif_esp32s3_devkitc_1_n8r8; codeformat.py / codespell / extract_pyi.py clean.
• On hardware (ESP32-S3), against an Android central:
  • Fresh pair: 6-digit value from pairing_numeric_comparison matches the phone's dialog → confirm_pairing(True) → authenticated is True, MITM bond stored.
  • Bonded reconnect after a power cycle: re-encrypts from the stored LTK, authenticated True, no new prompt.
  • LESC_ENCRYPT_WITH_MITM characteristic: unreadable before the bond, readable after. Repeated connect/disconnect cycles crash-free.
  • confirm_pairing(False) and abandoned-pairing paths: clean, no crash.

Open questions for reviewers

1. Perm-derived adapter IO capability vs. an explicit Adapter property. Deriving sm_io_cap from *_WITH_MITM characteristic perms is zero-config and safe-by-default, but it's a global side effect of constructing an attribute and it's sticky. Would an explicit adapter.io_capability = ... (or similar) be preferred, either instead or in addition (e.g. for a device that wants numeric comparison without an MITM characteristic)?
2. Same PR or fast-follow for nordic? Bundling nordic pulls in an ECDH submodule and a much larger review surface. Is "espressif + honest stubs + tracked follow-up issue" acceptable for landing the shared-bindings API, or should nordic be in this PR?
3. confirm_pairing() raising vs. no-op on "nothing pending." Went with raising to match _bleio norms (__init__.c raises "Already in progress" for the mirror case); the poll→confirm race is narrow and inside the exception envelope a real client already needs. Happy to switch to silent return if that's the house preference.

Related

A separate issue: on this NimBLE build a client GATT procedure (discover_remote_services() + reads) running concurrently with an inbound SM pairing procedure on the same connection silently kills pairing — PASSKEY_ACTION never fires. Not caused by this change and worked around downstream by deferring the client read until after the bond, but worth an issue of its own.